<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>IupMatrix</title>
<link rel="stylesheet" type="text/css" href="../../style.css">
<style type="text/css">
  .auto-style1 {
	font-family: "Courier New", Courier, monospace;
}
  </style>
</head>
<body>
<div id="navigation">
  <ul>
    <li><a href="#Creation">Creation</a></li>
    <li><a href="#Attributes">Attributes</a></li>
    <li><a href="#Callbacks">Callbacks</a></li>
    <li><a href="#Notes">Notes</a></li>
    <li><a href="#Examples">Examples</a></li>
    <li><a href="#SeeAlso">See Also</a></li>
  </ul>
</div>

<h2>IupMatrix</h2>
<p>Creates a matrix of alphanumeric fields. 
  Therefore, all values of the matrix fields are strings. The matrix is not a grid container like many systems 
  have. It inherits from 
<a href="../elem/iupcanvas.html">IupCanvas</a>.</p>
<p>This is an additional control that depends on the CD library. It is included 
in the 
<a href="../iupcontrols.html">IupControls</a> library.</p>
<p>It has two modes of operation: normal and callback mode. In normal mode, string values are stored in attributes for 
  each cell. In callback mode these attributes are ignored and the cells are filled with strings returned by the &quot;VALUE_CB&quot; 
  callback. So the existence of this callback defines the mode the matrix will operate.</p>
<h3><a name="Creation">Creation</a></h3>
<div>
  <pre>Ihandle* IupMatrix(char *<strong>action_cb</strong>); [in C]
iup.matrix{} -&gt; (<strong>ih</strong>: ihandle) [in Lua]
matrix(<strong>action_cb</strong>) [in LED]</pre>
</div>
<p><strong>action_cb</strong>:
  Name of the action generated when the user 
  types something.</p>
<p>Returns the identifier of the created 
  matrix, or NULL if an error occurs.</p>
<h3><a name="Attributes">Attributes</a></h3>


<h4>See <a href="iupmatrix_attrib.html#General_Attributes">General Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Cell_Attributes">Cell Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Column_Attributes">Column Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Size_Attributes">Size Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Column_Size_Attributes">Column Size 
Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Line_Size_Attributes">Line Size 
Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Number_of_Cells_Attributes">Number of Cells 
Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Mark_Attributes">Mark Attributes 
Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Merg_Attributes">Merge Attributes 
Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Action_Attributes">Action Attributes 
Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Editing_Attributes">Editing Attributes 
Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Text_Editing_Attributes">Text Editing Attributes 
Attributes</a></h4>
<h4>See <a href="iupmatrix_attrib.html#Canvas_Attributes">Canvas Attributes 
Attributes</a></h4>
<h3><a name="Callbacks">Callbacks</a></h3>

<h4>Interaction</h4>
<p class="info">
<a href="iupmatrix_cb.html#ACTION_CB">ACTION_CB</a> -
    Action generated when a keyboard event 
    occurs.<a href="iupmatrix_cb.html#CLICK_CB"><br>
    CLICK_CB</a> -
    Action generated when any mouse button is 
    pressed over a cell.<br>
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">
<a href="iupmatrix_cb.html#COLRESIZE_CB">COLRESIZE_CB</a></span><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">: 
Action generated when a column is interactively resized.<span class="Apple-converted-space">&nbsp;</span></span><a href="iupmatrix_cb.html#DRAW_CB"><br>
</a><a href="iupmatrix_cb.html#RELEASE_CB">RELEASE_CB</a> -
    Action generated when any mouse button is 
    released over a cell.<br>
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">
<a href="iupmatrix_cb.html#RESIZEMATRIX_CB">RESIZEMATRIX_CB</a></span><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">: 
Action generated after the element size has been updated but before the cells 
have been actually refreshed.<span class="Apple-converted-space">&nbsp;</span></span><br>
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">
<a href="iupmatrix_cb.html#TOGGLEVALUE_CB">TOGGLEVALUE_CB</a></span><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">: 
Action generated when a toggle button is pressed.</span><br>
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">
<a href="iupmatrix_cb.html#VALUECHANGED_CB">VALUECHANGED_CB</a></span><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">: 
Called after the value was interactively changed by the user or after a group of 
values where programmatically changed in a single operation.</span><a href="iupmatrix_cb.html#DRAW_CB"><br>
</a><a href="iupmatrix_cb.html#MOUSEMOVE_CB">MOUSEMOVE_CB</a> -
    Action generated to notify the application 
    that the mouse has moved over the matrix.<br>
<a href="iupmatrix_cb.html#ENTERITEM_CB">ENTERITEM_CB</a> -
    Action generated when a matrix cell is 
    selected, becoming the current cell.<a href="iupmatrix_cb.html#LEAVEITEM_CB"><br>
    LEAVEITEM_CB</a> -
    Action generated when a cell is no longer 
    the current cell.<br>
<a href="iupmatrix_cb.html#SCROLL_CB">SCROLLTOP_CB</a> -
    Action generated when the matrix is scrolled 
    with the scrollbars or with the keyboard.</p>
<h4>Drawing</h4>
<p class="info">
<a href="iupmatrix_cb.html#BGCOLOR_CB">BGCOLOR_CB</a> -
    Action generated to retrieve the background 
    color of a cell when it needs to be redrawn. 
    <br>
    <a href="iupmatrix_cb.html#FGCOLOR_CB">FGCOLOR_CB</a> -
    Action generated to retrieve the foreground 
    color of a cell when it needs to be redrawn. 
    <br>
    <a href="iupmatrix_cb.html#FONT_CB">FONT_CB</a> -
    Action generated to retrieve the font 
    of a cell when it needs to be redrawn. 
    <br>
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">
<a href="iupmatrix_cb.html#TYPE_CB">TYPE_CB</a></span><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">: 
Action generated to retrieve the type of a cell value.<span class="Apple-converted-space">&nbsp;</span></span><br>
    <a href="iupmatrix_cb.html#DRAW_CB">DRAW_CB</a> -
    Action generated before the cell is drawn. 
    Allow a custom cell draw.<br>
<a href="iupmatrix_cb.html#DROPCHECK_CB">DROPCHECK_CB</a> -
    Action generated to determine if a dropdown 
    feedback should be shown.<br><a href="iupmatrix_cb.html#TRANSLATEVALUE_CB">TRANSLATEVALUE_CB</a>:
  Action generated to translate the value of a 
  cell during display and size computation. </p>
<h4>Editing</h4>
<p class="info">
<a href="iupmatrix_cb.html#DROP_CB">DROP_CB</a> -
    Action generated to determine if a text 
    field or a dropdown will be shown.<br>
<a href="iupmatrix_cb.html#MENUDROP_CB">MENUDROP_CB</a> - Action generated to 
determine if a popup menu will be shown.&nbsp; <br>
<a href="iupmatrix_cb.html#DROPSELECT_CB">DROPSELECT_CB</a> -
    Action generated when an element in the 
    dropdown list is selected.<a href="iupmatrix_cb.html#EDITION_CB"><br>
    EDITION_CB</a> -
    Action generated when the current cell 
    enters or leaves the edition mode.</p>
<h4>Callback Mode</h4>
<p class="info">
<a href="iupmatrix_cb.html#VALUE_CB">VALUE_CB</a> -
    Action generated to verify the value of a 
    cell. 
    <br>
<a href="iupmatrix_cb.html#VALUE_EDIT_CB">VALUE_EDIT_CB</a> -
    Action generated to notify the application 
    that the value of a cell was edited. <br>
<a href="iupmatrix_cb.html#MARK_CB">MARK_CB</a> -
    Action generated to verify the selection 
    state of a cell. <a href="iupmatrix_cb.html#MARKEDIT_CB"><br>
    MARKEDIT_CB</a> -
    Action generated to notify the application 
    that the selection state of a cell was changed. 
  </p>
<h3>Utility Functions </h3>
<p>These functions can be used to help set and get attributes from the matrix:</p>
<pre>void  IupSetAttributeId2(Ihandle* ih, const char* name, int lin, int col, const char* value);
char* IupGetAttributeId2(Ihandle* ih, const char* name, int lin, int col);
int   IupGetIntId2(Ihandle* ih, const char* name, int lin, int col);
float IupGetFloatId2(Ihandle* ih, const char* name, int lin, int col);
void  IupSetfAttributeId2(Ihandle* ih, const char* name, int lin, int col, const char* format, ...);
void  IupSetIntId2(Ihandle* ih, const char* name, int lin, int col, int value);
void  IupSetFloatId2(Ihandle* ih, const char* name, int lin, int col, float value);</pre>
<p>They work just like the respective traditional set and get functions. But the attribute string is complemented with 
  the L and C values. When only one value is needed then use the Iup*AttributeId 
functions. For ex:</p>
<pre>IupSetAttribute(ih, &quot;30:10&quot;, value)        =&gt; IupSetAttributeId2(ih, &quot;&quot;, 30, 10, value)
IupSetAttribute(ih, &quot;BGCOLOR30:10&quot;, value) =&gt; IupSetAttributeId2(ih, &quot;BGCOLOR&quot;, 30, 10, value)
IupSetAttribute(ih, &quot;ALIGNMENT10&quot;, value)  =&gt; IupSetAttributeId(ih, &quot;ALIGNMENT&quot;, 10, value)</pre>
<p>When one of the indices is the asterisk, use IUP_INVALID_ID as the parameter. 
For ex:</p>
<pre>IupSetAttribute(ih, &quot;BGCOLOR30:*&quot;, value) =&gt; IupSetAttributeId2(ih, &quot;BGCOLOR&quot;, 30, IUP_INVALID_ID, value)</pre>
<p>These functions are faster than the traditional functions because they do 
not need to parse the attribute name string and the application does not need to 
concatenate the attribute name with the id.</p>
<p>They are used by the additional methods in Lua:</p>
<pre><strong>ih</strong>:setcell(<strong>lin, col</strong>: number, <strong>value</strong>: string)
<strong>ih</strong>:getcell(<strong>lin, col</strong>: number) -&gt; (<strong>cell</strong>: string)</pre>
<p>But you can also use the traditional functions when typing:</p>
<pre><strong>ih</strong>[&quot;bgcolor&quot;..l..&quot;:&quot;..c] = v
   or
<strong>ih</strong>[&quot;bgcolor30:10&quot;] = v</pre>
<hr>
<pre>void <b>IupMatrixSetFormula</b>(Ihandle* <b>ih</b>, int <strong>col</strong>, const char* <strong>formula</strong>, const char* <strong>init</strong>); [in C]
<b>iup.MatrixSetFormula</b>(<b>ih</b>: ihandle, <strong>col</strong>: number, <strong>formula</strong>: string, [<strong>init</strong>: string]) [in Lua]
or <strong>ih</strong>:SetFormula(<strong>col</strong>: number, <strong>formula</strong>: string, [<strong>init</strong>: string]) [in Lua]</pre>
<p>Fill the contents of the given column using the formula (since 3.13). The 
formula is executed for each line within the column. Internally uses
<a href="http://www.lua.org" target="_blank">Lua</a> to parse the formula.
<strong>init</strong> is an optional Lua initialization code that is called only 
once (can be NULL). The callback <span class="auto-style1">&quot;int <strong>FORMULAINIT_CB</strong>(Ihandle* 
ih, lua_State *L);</span>&quot; can also be used to initialize the Lua state. All 
Lua standard libraries are pre-loaded.</p>
<p>This function is available in the &quot;iupluacontrols&quot; library but it does not 
requires an active Lua context, because it uses a temporary Lua context. If 
called from Lua it will also be independent from the application's Lua context. 
To use it in C/C++ you must link also with Lua and iuplua even when not using 
theses libraries directly.</p>
<p>The formula will be encapsulated within an internal Lua function so it will 
not affect the call of subsequent cells. This internal function receives two 
parameters &quot;lin&quot; and &quot;col&quot; correspondent to the current cell being processed 
during script execution. The formula can contain only one valid Lua statement that will 
be retuned by the internal Lua function. The formula can evaluate to nil, 
number, boolean or a string. </p>
<p>The most commonly used tokens are:</p>
<pre style="font-size: medium; color: rgb(0, 0, 0); font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: justify; text-indent: 0px; text-transform: none; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;">+&nbsp; (addition)&nbsp;
-&nbsp; (subtraction and negation)&nbsp;
*&nbsp; (multiplication)&nbsp;
/&nbsp; (division)&nbsp;
%&nbsp; (modulo)
^&nbsp; (exponentiation)
== (equal)
~= (different)
&lt;  (less than)
&gt;  (greater than)
&lt;= (less than or equal)
&gt;= (greater than or equal)
and (logical and)
or  (logical or)
not (logical not)</pre>
<p>The Lua
<a href="http://www.lua.org/manual/5.2/manual.html#6.6" target="_blank">Math 
Functions</a> are loaded also at the global level, so there is no need for the 
&quot;math.&quot; prefix. The most commonly used functions are:</p>
<pre><strong>abs</strong>(x)    <strong>acos</strong>(x)    <strong>asin</strong>(x)    <strong>atan</strong>(x)    <strong>atan2</strong>(y,x)    <strong>ceil</strong>(x)    <strong>cos</strong>(x)
<strong>deg</strong>(x)    <strong>exp</strong>(x)     <strong>floor</strong>(x)   <strong>log</strong>(x)     <strong>min</strong>(x,...)    <strong>max</strong>(x,...) <strong>pow</strong>(x,y)
<strong>sin</strong>(x)    <strong>sqrt</strong>(x)    <strong>tan</strong>(x)</pre>
<p>There are also some exclusive functions to access cell values and perform 
special operations:</p>
<pre><strong>sum</strong>(x,...)  - computes the sum of the input paramters.
<strong>average</strong>(x,...)  - computes the average of the input paramters.
<strong>range</strong>(lin1, col1, lin2, col2[, only_number]) - returns a range of cell values. 
                     Can be used in functions like min, max, sum and average.
                     If only_number boolean is used then only numbers are included, 
                     and others are skipped.
<strong>cell</strong>(lin, col) - returns the cell value at given line and column.
<strong>ifelse</strong>(test, value_true, value_false) - if test boolean is true then return value_true,
                                        if not return value_falseor else.
       The problem with ifelse is that both values are evaluated before calling the function.
       In Lua the solution is to use logical operators:
       test <strong>and</strong> value_true <strong>or</strong> value_false
       (but value_true can not be <strong>false</strong>)
       See <a href="http://lua-users.org/wiki/TernaryOperatorhttp://lua-users.org/wiki/TernaryOperator" target="_blank">http://lua-users.org/wiki/TernaryOperator</a></pre>
<p>If the attribute CELLNAMES is set to &quot;Excel&quot; or &quot;Matrix&quot; (default &quot;No&quot;) then it will enable 
cell names to be used as alternative for &quot;cell(lin, col)&quot;. There are two notations 
available: the Matrix &quot;L123C123&quot; notation where L and C are fixed and 
123s are the line and columns numbers; and the Excel &quot;ABC123&quot; notation where 123 
denotes the line number and ABC denotes the column number just like in Microsoft 
Excel. (since 3.14) Obs: there is not support for cell range like &quot;A1:B2&quot; in 
Excel.</p>
<p>Some formula examples:</p>
<pre>&quot;cos(pi*<strong>lin</strong>/4)&quot;
&quot;cell(<strong>lin</strong>, 1) + cell(<strong>lin</strong>, 2)&quot;
&quot;cell(<strong>lin</strong>, 4) &lt; 3&quot;  -- cell value will be 0 or 1
&quot;sum(range(<strong>lin</strong>, 1, <strong>lin</strong>, 7))&quot;
&quot;cell('x', 1)&quot;  -- error</pre>


<hr>
<pre>void <b>IupMatrixSetDynamic</b>(Ihandle* <b>ih</b>, const char* <strong>init</strong>); [in C]
<b>iup.MatrixSetDynamic</b>(<b>ih</b>: ihandle, [<strong>init</strong>: string]) [in Lua]
or <b>ih:</b>SetDynamic([<strong>init</strong>: string]) [in Lua]</pre>
<p>Enable dynamic cell values using formulas (since 3.13). It uses the 
TRANSLATEVALUE_CB callback to process strings just before the value is 
displayed, if the string starts with a equal sign (&quot;=&quot;) then it is interpreted 
as a formula using the same features and rules as the <b>IupMatrixSetFormula</b> 
function above. If the value is being edited the callback will return the 
original value so the formula can be edited.</p>
<p>Internally also uses
<a href="http://www.lua.org" target="_blank">Lua</a> to parse the formula.
<strong>init</strong> is an optional Lua initialization code that is called only 
once (can be NULL), at the function call. The callback <span class="auto-style1">&quot;int
<strong>FORMULAINIT_CB</strong>(Ihandle* 
ih, lua_State *L);</span>&quot; can also be used to initialize the Lua state, at 
the function call. All Lua standard libraries are pre-loaded.</p>
<p>This Lua state is initialize at the function call and saved for processing during the TRANSLATEVALUE_CB callback. 
If IupMatrixSetDynamic is called again then the previous state will be destroyed and a new one will be 
created. This state is automatically destroyed when the control is destroyed.</p>
<p>This function is available in the &quot;iupluacontrols&quot; library but it does not 
requires an active Lua context, because it uses a temporary Lua context. If 
called from Lua it will also be independent from the application's Lua context. 
To use it in C/C++ you must link also with Lua and iuplua even when not using 
theses libraries directly.</p>
<p>If the cell has a formula, i.e. starts with the equal sign, and the attribute 
EDITHIDEONFOCUS is NO, then during editing the user can click on another cell to 
insert a reference to its value in the format &quot;cell(lin,col)&quot;. If CELLNAMES is 
enabled then the respective cell name will be used instead of the &quot;cell&quot; 
function call. Selecting a range of cells it will insert a 
&quot;range(lin1,col1,lin2,col2)&quot; call instead (there is no special notation for a 
range). (since 3.14)</p>
<h3><a name="Notes">Notes</a></h3>
<h4>Storage</h4>
<p>Before mapped to the native system, all attributes are stored in the hash 
table, independently from the size of the matrix or its operation mode. The 
action attributes like ADDLIN and DELCOL will NOT work.</p>
<p>When the matrix is mapped, and it is NOT in callback mode, then the cell values and 
mark state are moved from the hash table to an internal storage at the matrix. 
Other cell attributes remains on the hash table. Cell values with indices 
greater than (NUMLIN,NUMCOL) are ignored. When in callback mode cell 
values stored in the hash table are ignored.</p>
<h4>Callback Mode</h4>
<p>Very large matrices can use the callback 
  mode to store the cell values at the application, and not at the internal 
matrix storage. The idea is the following:</p>
<p>1 -
    Register the VALUE_CB callback<br>
    2 -
    No longer set the value of the cells. Store the cell value at the 
application. They 
    will be retrieved one by one by the callback.<br>
    3 -
    If the matrix can be edited, set the VALUE_EDIT_CB callback.<br>
    4 -
    When the matrix display must be updated, use the REDRAW attribute to force a matrix redraw.</p>
<p>A negative aspect is that, when VALUE_CB is defined, after it is mapped the matrix never verifies attributes of type 
L:C again.</p>
<p>If VALUE_CB is defined and VALUE_EDIT_CB is not defined when the matrix is 
mapped then READONLY will be set to YES.</p>
<h4>Number of Cells</h4>
<p>If you do not plan to use ADDLIN nor ADDCOL, and plan to set sparse cell 
values, then you must set NUMLIN and 
NUMCOL before mapping.</p>
<h4>Titles</h4>
<p>A matrix might have titles for lines and columns. Titles are always non scrollable, 
non editable and presented with a different default background color. A matrix 
will have a line of titles if an attribute of the &quot;<em>L</em>:0&quot; type is defined, where L 
is a line number, or if the HEIGHT0 attribute is defined. It will have a column of titles if an attribute of the 
&quot;0:<em>C</em>&quot; type is defined, where C is a column number, or if the 
WIDTH0 attribute is defined.</p>
<p>When allowed the
  width of a column can be changed by holding and dragging its title right border, 
see RESIZEMATRIX.</p>
<p>Any cell can have more than one text line, just use the \n control character. 
Multiple text lines will be considered when calculating the title cell size 
based on its contents. The contents of ordinary cells (not a title) do not 
affect the cell size.</p>
<h4>Natural Size</h4>
<p>The Natural size is calculated using only the 
title cells size plus the size of NUMCOL_VISIBLE and NUMLIN_VISIBLE cells, but it is also affected if SCROLBAR is 
enabled. The natural height is the sum of the line heights from line 0 to 
NUMLIN_VISIBLE (inclusive). The natural width is the sum of the column width 
from column 0 to NUMCOL_VISIBLE (inclusive). Notice that since NUMCOL_VISIBLE 
and NUMLIN_VISIBLE do not include the titles then NUMCOL_VISIBLE+1 columns and 
NUMLIN_VISIBLE+1 lines are included in the sum.</p>
<p>The height of a line L depends on several attributes, first it checks the 
HEIGHT<em>L</em> attribute, then checks RASTERHEIGHT<em>L</em>, then when 
USETITLESIZE=YES or not in callback mode the height 
of the title text for the line or if L=0 it searches for the highest column 
title, if still could not define a height then if L!=0 it will use HEIGHTDEF, if 
L=0 then height will be 0.</p>
<p>A similar approach is valid for the column width. The 
width of a column C first checks the WIDTH<em>C</em> attribute, then checks 
RASTERWIDTH<em>C</em>, then when USETITLESIZE=YES or not in callback mode the width of the title text for the column or if C=0 
it searches for the widest line title, if still could not define a width then if 
C!=0 it will use WIDTHDEF, if C=0 then height will be 0.</p>
<h4>Virtual Size</h4>
<p>When the scrollbars are enabled if the matrix area is greater than the 
visible area then scrollbars will be displayed so the cells can be scrolled to 
be visible area. When dragging the scrollbar the position of cells is free, when 
clicking on its buttons it will move in cell steps, aligning to the left border 
of the cell.</p>
<p>By default EXPAND=Yes, so matrix will be automatically resized when the 
dialog is resized. So more columns and lines will be displayed. But the matrix 
Natural size will be used as minimum size. To remove the minimum size limitation set 
NUMCOL_VISIBLE and NUMLIN_VISIBLE to 0 after showing it for the first time.</p>
<h4>Edition Mode</h4>
<p>When READONLY=NO and there is no EDITION_CB callback or the callback return 
is
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">
IUP_DEFAULT, the matrix cell values can be edited. </span></p>
<p>
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.7999992370605px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; display: inline !important; float: none; background-color: rgb(255, 255, 255);">
Editing starts automatically when the user press a character key when the focus 
is at a cell, then the old cell value is replaced by the new one being typed. I</span>f <b>F2, Enter</b> or 
<b>Space</b> is pressed, the current cell enters the edition mode with the 
current text of the cell. And double-clicking a cell  
  enters the edition mode (in Motif the 
  user must click again to the edit control get the focus).</p>
<p>The new value will be accepted if the user press <strong>Enter</strong> 
during edition mode. Pressing <strong>Esc</strong> will cancel the editing and 
the the old value remains. The cell will also leave the edition mode if the user clicked 
  in another cell or in another control, then the new value will be 
automatically accepted. But the value confirmation still depends on the
  EDITION_CB callback return code.</p>
<h4>Keyboard Navigation</h4>
<p>Keyboard navigation through the matrix cells outside the edition 
  mode is done by using the following keys:</p>
<ul>
  <li><strong>Arrows</strong>: Moves the focus to the next cell, according to 
    the arrows direction.</li>
  <li><strong>Page Up</strong> and <strong>Page Down</strong>: Moves a visible page up or down.</li>
  <li><strong>Home</strong>: Moves the focus to the fist column in the line.</li>
  <li><strong>Home</strong> <strong>Home</strong>: Moves the focus to the top-left corner of the 
    visible page.</li>
  <li><strong>Home</strong> <strong>Home</strong> <strong>Home</strong>: 
    Moves the focus to the top-left corner of the 
    first page of the matrix.</li>
  <li><strong>End</strong>: Moves the focus to the last column in the line.</li>
  <li><strong>End</strong> <strong>End</strong>: Moves the focus to the bottom-right corner of the 
    visible page.</li>
  <li><strong>End</strong> <strong>End</strong> <strong>End</strong>: Moves the focus to the 
  bottom-right corner of the 
    last page in the matrix.</li>
</ul>
<p>When using the keyboard to change the focus cell if the limit of the visible 
area is reached then the cells are automatically scrolled. Also if a cell 
partially visible is edited then first it is scrolled to the visible area. Also 
while pressing together the <strong>Shift</strong> key and marks are enabled 
with MARKMULTIPLE=Yes then a continuous area will be selected (since 3.9).</p>
<p>Inside the <b>edition mode</b>, the 
  following keys are used 
  for a text field:</p>
<ul>
  <li><strong>Left, Right, Up and Down arrows</strong>: if the caret is at the extremes of the text 
    being edited then leave the edition mode and moves the focus accordingly. 
	The value is confirmed.</li>
  <li><strong>Ctrl + arrows</strong>:
    leave the edition mode and moves the focus 
    accordingly independent of caret position. The value is confirmed.</li>
	<li><strong>Enter</strong>: leave the edition mode. The value is confirmed. 
	Moves the focus to the cell below.</li>
	<li><strong>Esc</strong>: leave the edition mode. The new value is ignored 
	and the old value remains.</li>
</ul>
<p>When pressing 
<b>Enter</b> 
  to confirm the value the focus goes to the cell below the current cell, if at 
the last line then the focus goes to the cell on the left. This can be 
controlled using the EDITNEXT attribute.</p>
<h4>Marks (Selected Cells)</h4>
<p>When a mark mode is set the cells can be marked using mouse.</p>
<p>A marked cell will have its background attenuated to indicate that it is marked. 
A title cell appears marked only when MARKMODE=LIN, COL or LINCOL.</p>
<p>Cells can be selected individually or can be restricted to lines or columns. Also multiple cells can 
  be marked simultaneously in continuous or in segmented areas. Lines and columns are marked only when the user clicks 
  in their respective titles, if MARKMODE=CELL then all the cells of the line 
or column will be marked. Continuous areas are marked holding and dragging the mouse or holding the 
<b>Shift</b> 
  key when clicking at the end of the area. Segmented areas are marked or 
unmarked holding the <b>Ctrl</b> key, the mark state is inverted. Clicking on 
the cell 0:0 will select all the cells depending on MARKMODE, except for 
LINCOL.</p>
<p>When there are cells marked, pressing the <strong>Del</strong> key remove the 
selected cells contents.</p>
<h4>IupMatrixEx</h4>
<p>For more features, like Import/Export, Clipboard, Undo/Redo, Search, Sort, 
Column Visibility, Numeric Columns, Numeric, Context Menu and others, see the
<a href="iupmatrixex.html">IupMatrixEx</a> extension library.</p>
<h3><a name="Examples">Examples</a></h3>
<p><a href="../../examples/">Browse for Example Files</a></p>
<p align="center">
<img src="images/iupmatrix1.png"></p>
<p align="center">
<img src="images/iupmatrix2.png"></p>
<h3><a name="SeeAlso">See Also</a></h3>

<p><a href="../elem/iupcanvas.html">IupCanvas</a>, <a href="iupmatrixex.html">
IupMatrixEx</a></p>

</body>

</html>